---
title: gluestack-ui Select | Installation, Usage, and API

description: Present options conveniently in a collapsible view, allowing users to expand and select items from a dropdown list.

pageTitle: Select

pageDescription: Present options conveniently in a collapsible view, allowing users to expand and select items from a dropdown list.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Components/Forms/Select" />

import {
  Select,
  SelectIcon,
  SelectTrigger,
  SelectInput,
  SelectPortal,
  SelectBackdrop,
  SelectContent,
  SelectDragIndicatorWrapper,
  SelectDragIndicator,
  SelectItem,
  Icon,
  ChevronDownIcon,
  FormControl,
  FormControlLabel,
  FormControlLabelText,
  FormControlHelper,
  FormControlHelperText,
  FormControlError,
  FormControlErrorIcon,
  FormControlErrorText,
  AlertCircleIcon,
} from '../../core-components/nativewind';
import { transformedCode } from '../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  Tabs,
  InlineCode,
  CollapsibleCode,
} from '@gluestack/design-system';
import Wrapper from '../../core-components/nativewind/Wrapper';
import AnatomyImage from '../../extra-components/nativewind/AnatomyImage';

This is an illustration of **Select** component.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
        <Select>
          <SelectTrigger {...props}>
            <SelectInput placeholder="Select option" />
            <SelectIcon className="mr-3" as={ChevronDownIcon} />
          </SelectTrigger>
          <SelectPortal>
            <SelectBackdrop/>
            <SelectContent>
              <SelectDragIndicatorWrapper>
                <SelectDragIndicator />
              </SelectDragIndicatorWrapper>
              <SelectItem label="UX Research" value="ux" />
              <SelectItem label="Web Development" value="web" />
              <SelectItem
                label="Cross Platform Development Process"
                value="Cross Platform Development Process"
              />
              <SelectItem
                label="UI Designing"
                value="ui"
                isDisabled={true}
              />
              <SelectItem
                label="Backend Development"
                value="backend"
              />
            </SelectContent>
          </SelectPortal>
        </Select>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        Select,
        SelectTrigger,
        SelectInput,
        SelectIcon,
        SelectPortal,
        SelectBackdrop,
        SelectContent,
        SelectDragIndicatorWrapper,
        SelectDragIndicator,
        SelectItem,
        Icon,
        ChevronDownIcon,
      },
      argsType: {
        variant: {
          control: 'select',
          options: ['rounded', 'outline', 'underlined'],
          default: 'outline',
        },
        size: {
          control: 'select',
          options: ['sm', 'md', 'lg', 'xl'],
          default: 'md',
        },
      },
    }}
  />
</Wrapper>

<br />

## Installation

<Tabs value="cli" type="section">
  <Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>CLI</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>

### Run the following command:
  ```bash
  npx gluestack-ui add select
  ```
</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>

### Step 1: Install the following dependencies:
```bash
npm i @gluestack-ui/select
```

### Step 2: Copy and paste the following code into your project.
<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/select/index.tsx --%% 
```
</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import { Select, SelectTrigger, SelectInput, SelectIcon, SelectPortal, SelectBackdrop, SelectContent, SelectDragIndicatorWrapper, SelectDragIndicator, SelectItem } from '@/components/ui/select';
```

<AnatomyImage mobileUrl='https://i.imgur.com/g0lTtcB.png' webUrl='https://i.imgur.com/cX9uCot.png' classNameStyle='aspect-[513/397] md:aspect-[736/237]' />

```jsx
export default () => (
  <Select>
    <SelectTrigger>
      <SelectInput />
      <SelectIcon>
        <Icon />
      </SelectIcon>
    </SelectTrigger>
    <SelectPortal>
      <SelectBackdrop />
      <SelectContent>
        <SelectDragIndicatorWrapper>
          <SelectDragIndicator />
        </SelectDragIndicatorWrapper>
        <SelectItem />
      </SelectContent>
    </SelectPortal>
  </Select>
);
```

### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### Select

Contains all Select related layout style and high-level select props.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

> Note: Please note that this select component renders as an Actionsheet on `iOS` and `Android` devices for a native feel. On `web`, it behaves like a regular select element and renders the default HTML options.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the select is disabled and cannot be edited.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isInvalid</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the select displays an error state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isRequired</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, sets aria-required="true" on the input.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isHovered</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the select displays a hover state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isFocusVisible</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the focus ring of select will be visible.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isFocused</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the select displays a focus state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>closeOnOverlayClick</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the select will close when the overlay is clicked.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>selectedValue</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Sets the currently selected option value, allowing the component to render with the corresponding option pre-selected.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>initialLabel</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>string</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Sets the initial selected Label for a select component.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>defaultValue</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Sets the initial selected option value for a select component.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onOpen</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`() => any`}</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback to be invoked when Select Dropdown or Actionsheet is opened.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onValueChange</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`() => any`}</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback to be invoked when Select value is changed.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onClose</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`() => any`}</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback to be invoked when Select Dropdown or Actionsheet is closed.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

> Note: Please note that if you want to use `initialLabel` prop, then you also need to pass `defaultValue` or `selectedValue` prop, to select the option value for a select component.

#### SelectTrigger

It inherits all the properties of React Native's [Pressable](https://reactnative.dev/docs/pressable) component.

#### SelectInput

It inherits all the properties of React Native's [TextInput](https://reactnative.dev/docs/textInput) component.

#### SelectIcon

It inherits all the properties of React Native's [Pressable](https://reactnative.dev/docs/pressable) component.

#### SelectPortal

It is internally mapped wth gluestack-ui's [Actionsheet](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### SelectBackdrop

It is internally mapped wth gluestack-ui's [ActionsheetBackdrop](https://ui.gluestack.io/docs/components/disclosure/actionsheet) component, which is React Native's [Pressable](https://reactnative.dev/docs/pressable) component, created using [@legendapp/motion's](https://legendapp.com/open-source/motion/) `createMotionAnimatedComponent` function to add animation to the component. You can use any declarative animation library you prefer.

#### SelectContent

It is internally mapped wth gluestack-ui's [ActionsheetContent](https://ui.gluestack.io/docs/components/disclosure/actionsheet) component, which inherits all the properties of [@legendapp/motion's](https://legendapp.com/open-source/motion/) [Motion.View](https://legendapp.com/open-source/motion/overview/) component. With this ActionSheet component, you have the flexibility to use any declarative animation library that suits your needs.

#### SelectDragIndicatorWrapper

It is internally mapped wth gluestack-ui's [ActionsheetDragIndicatorWrapper](https://ui.gluestack.io/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### SelectDragIndicator

It is internally mapped wth gluestack-ui's [ActionsheetDragIndicator](https://ui.gluestack.io/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### SelectItem

It internally uses gluestack-ui's [ActionsheetItem](https://ui.gluestack.io/docs/components/disclosure/actionsheet) and [Actionsheet.ItemText](https://ui.gluestack.io/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [Pressable](https://reactnative.dev/docs/pressable) component.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, its disabled state activates.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>label</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>string</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`setting label that displays to the user.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>value</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>string</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`The value to be used for the item. This is the value that will be returned on form submission.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>textStyle</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>inherits all the properties of react native text</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`This prop only works on native.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

#### SelectScrollView

It is internally mapped wth gluestack-ui's [Actionsheet.ScrollView](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [ScrollView](https://reactnative.dev/docs/scrollview#props) component.

#### SelectVirtualizedList

It is internally mapped wth gluestack-ui's [Actionsheet.VirtualizedList](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [VirtualizedList](https://reactnative.dev/docs/virtualizedlist#props) component.

#### SelectFlatList

It is internally mapped wth gluestack-ui's [Actionsheet.FlatList](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [FlatList](https://reactnative.dev/docs/flatlist#props) component.

#### SelectSectionList

It is internally mapped wth gluestack-ui's [Actionsheet.SectionList](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [SectionList](https://reactnative.dev/docs/sectionlist#props) component.

#### SelectSectionHeaderText

It is internally mapped wth gluestack-ui's [Actionsheet.SectionHeaderText](/ui/docs/components/disclosure/actionsheet) component, which inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text#props) component.

### Features

- Support for native and web platforms separately.
- Support for passing custom trigger.

### Accessibility

We have outlined the various features that ensure the Select component is accessible to all users, including those with disabilities.These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the [WAI-ARIA design pattern](https://react-spectrum.adobe.com/react-aria/Selecthtml).

#### Keyboard

- `Tab + Space`: Triggers the select's action.

#### Screen Reader

- VoiceOver: When the select is focused, the screen reader will announce the select content.

### Props

Select component is created using View component from react-native. It extends all the props supported by [React Native View](https://reactnative.dev/docs/view#props) and the props mentioned below.

#### Select

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Name</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Value</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>size</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>sm | md | lg | xl</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>md</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>variant</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>underlined | outline | rounded</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>outline</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

### Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

### Select FormControlled

The Select component with FormControl example demonstrates how to manage its state using the FormControl component. This allows for easy integration with forms and form validation.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <FormControl isRequired isInvalid>
          <FormControlLabel>
            <FormControlLabelText>
              Choose your favorite color
            </FormControlLabelText>
          </FormControlLabel>
          <Select>
            <SelectTrigger>
              <SelectInput placeholder="Select option"/>
              <SelectIcon className="mr-3" as={ChevronDownIcon} />
            </SelectTrigger>
            <SelectPortal>
              <SelectBackdrop />
              <SelectContent>
                <SelectDragIndicatorWrapper>
                  <SelectDragIndicator />
                </SelectDragIndicatorWrapper>
                <SelectItem label="Red" value="red" />
                <SelectItem label="Blue" value="blue" />
                <SelectItem label="Black" value="black" />
                <SelectItem label="Pink" value="pink" isDisabled={true} />
                <SelectItem label="Green" value="green" />
              </SelectContent>
            </SelectPortal>
          </Select>
          <FormControlHelper>
            <FormControlHelperText>
              You can only select one option
            </FormControlHelperText>
          </FormControlHelper>
          <FormControlError>
            <FormControlErrorIcon as={AlertCircleIcon} />
            <FormControlErrorText>Mandatory field</FormControlErrorText>
          </FormControlError>
        </FormControl>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        Select,
        SelectTrigger,
        SelectInput,
        SelectIcon,
        SelectPortal,
        SelectBackdrop,
        SelectContent,
        SelectDragIndicatorWrapper,
        SelectDragIndicator,
        SelectItem,
        Icon,
        ChevronDownIcon,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        AlertCircleIcon,
      },
      argsType: {},
    }}
  />
</Wrapper>
